Placements v1

The import/placements endpoints allows you to import the placements properties.

Authorisation

A function key is required. The name of Key must match Software Key

Request format

Method and URL

The HTTP method and URL is as follows:

HTTP

POST https://payandbill-cloud-api.azurewebsites.net/api/import/placements?version=1

Request Headers

Name	Type	Description
header	X-Functions-Key	Function Api Key
header	X-Software-Key	Software Key for this Integration

Request Body

Name	Type	Description
body	Placements[]	Placements schema

Request Body Example

Example Request Body

[
    {
        "EmployerRef": "ER1",
        "TaxYear": 2020,
        "TaxPeriod": 5,
        "TaxSession": 3,
        "PlacementRef": "123456",
        "DivisionRef": "DIV1",
        "DepartmentRef": "DEPT1",
        "ClientRef": "CLIENT1",
        "PersonnelRef": "WORKER1",
        "ApplicantName": "SampleWorker",
        "StartDate": "2020-02-05",
        "JobTitle": "Cleaner",
        "Salary": 1,
        "PlacementValue": 2,
        "CommissionPercentage": 20,
        "DebitOrCreditIndicator": "Credit",
        "PurchaseOrderNumber": "A0023698",
        "InvoiceDate": "2020-06-01",
        "ContractEndDate": "2020-12-15",
        "AdhocDescription": "Adhoc",
        "AdhocValue": 5.5,
        "PlacementCategory": "ContractPlacement",
        "SettlementDays": 5,
        "ReportToClientRef": "REPORTCLIENT",
        "InvoiceToClientRef": "INVOICECLIENT",
        "Comments": "Comments",
        "InvoiceAddressNo": 5,
        "ConsultantSplits": 
        [
        {
            "ConsultantRef": "CONSULT1",
            "Split": 45
        },
        {
            "ConsultantRef": "CONSULT2",
            "Split": 55
        }
        ]
    }
]

Responses

Name	Type	Description
200 Ok	Results[]	successful operation
400 Bad Request	string	Invalid Json request or Invalid DB Version
401 Unauthorized	string	Invalid/Missing API Key
403 Forbidden	string	Key name does not match Software Key
403 Forbidden	string	Integration missing for Software Key or disabled
403 Forbidden	string	Pay and Bill Database not active
501 Not Implemented	string	Message Type not found/implemented
501 Not Implemented	string	Payload data not supported

Response Example

Example Response

{
    "results": [
        {
            "recordIds": [
                {
                    "field": "EmployerRef",
                    "value": "ER1"
                },
                {
                    "field": "PlacementRef",
                    "value": "123456"
                }
            ],
            "importStatus": "OK",
            "errorCount": 0,
            "warningCount": 0,
            "infoCount": 0
        }
    ]
}

400 Response

Response when Invalid Json Request Body is sent to API.

Message will contain parsing error message.

400 Error Response

{
  "message": "<string>"
}

200 Response

A results array is returned which will include an item for each array item in the original request body.

Each item will identify the recordId's relevant for this message type.

Import Status, errorCount & warningCount will indicate the status of that row.

Messages will contain any error/warning messages relevant.

Note: Each row is treated as a separate commit to the database, so if multiple items are included in the import, the response will indicate which have been imported successfully & which have failed to import.

200 Ok Response

{  "results": [
    {
      "recordIds": [
          "field": "<string>",
          "value": "<string>"
       ],
       "importStatus": "<string>",
       "errorCount": <number>,
       "warningCount": <number>,
       "messages": [
         {
            "messageType": "<string>",
            "message": "<string>",
            "fieldName": "<string>"
         }
       ]
    }
  ]
}

Results

This is the response output from the import/placements endpoint

Property	Type	Defined
RecordIds	recordIds[]	Placements Results
ImportStatus	string	Placements Results
ErrorCount	integer	Placements Results
WarningCount	integer	Placements Results
InfoCount	integer	Placements Results
Messages	messages[]	Placements Results

RecordIds

A record id of the imported Placements

RecordIds

• Type: array

Property	Type	Defined
Field	string	Placements Results
Value	string	Placements Results

Example

{
    "recordIds": [
        {
            "field": "EmployerRef",
            "value": "ER1"
        },
        {
            "field": "PlacementRef",
            "value": "123456"
        }
    ]
}

ImportStatus

The import status of the request

ImportStatus

• Type: string

• defined in: Placements Results

ErrorCount

Number of errors in the request

ErrorCount

• Type: integer

• defined in: Placements Results

WarningCount

Number of warnings in the request

WarningCount

• Type: integer

• defined in: Placements Results

InfoCount

Number of Information messages in the request

InfoCount

• Type: integer

• defined in: Placements Results

Messages

An output of the info, warning or error messages.

Messages

• Type: array

Property	Type	Defined
MessageType	string	Placements Results
Message	string	Placements Results
FieldName	string	Placements Results
FieldValue	string	Placements Results
ErrorId	integer	Placements Results

Example

{
    "messages": [
        {
            "messageType": "Error",
            "message": "Value must be 10 characters or less and not contain lower case characters, '*' or '?'.",
            "fieldName": "ReportToClientRef",
            "fieldValue": "REPORTCLIENT",
            "errorID": 2002
        }
    ]
}